.TH std::function 3 "2024.06.10" "http://cppreference.com" "C++ Standard Libary"
.SH NAME
std::function \- std::function

.SH Synopsis
   Defined in header <functional>
   template< class >                   \fI(since C++11)\fP
   class function; /* undefined */
   template< class R, class... Args >  \fI(since C++11)\fP
   class function<R(Args...)>;

   Class template std::function is a general-purpose polymorphic function wrapper.
   Instances of std::function can store, copy, and invoke any CopyConstructible
   Callable target -- functions (via pointers thereto), lambda expressions, bind
   expressions, or other function objects, as well as pointers to member functions and
   pointers to data members.

   The stored callable object is called the target of std::function. If a std::function
   contains no target, it is called empty. Invoking the target of an empty
   std::function results in std::bad_function_call exception being thrown.

   std::function satisfies the requirements of CopyConstructible and CopyAssignable.

.SH Member types

   Type                                          Definition
   result_type                                   R
   argument_type(deprecated in C++17)(removed in T if sizeof...(Args)==1 and T is the
   C++20)                                        first and only type in Args...
   first_argument_type(deprecated in             T1 if sizeof...(Args)==2 and T1 is the
   C++17)(removed in C++20)                      first of the two types in Args...
   second_argument_type(deprecated in            T2 if sizeof...(Args)==2 and T2 is the
   C++17)(removed in C++20)                      second of the two types in Args...

.SH Member functions

   constructor        constructs a new std::function instance
                      \fI(public member function)\fP
   destructor         destroys a std::function instance
                      \fI(public member function)\fP
   operator=          assigns a new target
                      \fI(public member function)\fP
   swap               swaps the contents
                      \fI(public member function)\fP
   assign             assigns a new target
   (removed in C++17) \fI(public member function)\fP
   operator bool      checks if a target is contained
                      \fI(public member function)\fP
   operator()         invokes the target
                      \fI(public member function)\fP
.SH Target access
   target_type        obtains the typeid of the stored target
                      \fI(public member function)\fP
   target             obtains a pointer to the stored target
                      \fI(public member function)\fP

.SH Non-member functions

   std::swap(std::function) specializes the std::swap algorithm
   \fI(C++11)\fP                  \fI(function template)\fP
   operator==               compares a std::function with nullptr
   operator!=               \fI(function template)\fP
   (removed in C++20)

.SH Helper classes

   std::uses_allocator<std::function> specializes the std::uses_allocator type trait
   \fI(C++11)\fP \fI(until C++17)\fP              \fI(class template specialization)\fP

   Deduction guides\fI(since C++17)\fP

.SH Notes

   Care should be taken when a std::function, whose result type is a
   reference, is initialized from a lambda expression without a
   trailing-return-type. Due to the way auto deduction works, such lambda (until C++23)
   expression will always return a prvalue. Hence, the resulting
   reference will usually bind to a temporary whose lifetime ends when
   std::function::operator() returns.
   If a std::function returning a reference is initialized from a
   function or function object returning a prvalue (including a lambda
   expression without a trailing-return-type), the program is ill-formed  (since C++23)
   because binding the returned reference to a temporary object is
   forbidden.

 std::function<const int&()> F([] { return 42; }); // Error since C++23: can't bind
                                                   // the returned reference to a temporary
 int x = F(); // Undefined behavior until C++23: the result of F() is a dangling reference

 std::function<int&()> G([]() -> int& { static int i{0x2A}; return i; }); // OK

 std::function<const int&()> H([i{052}] -> const int& { return i; }); // OK

.SH Example


// Run this code

 #include <functional>
 #include <iostream>

 struct Foo
 {
     Foo(int num) : num_(num) {}
     void print_add(int i) const { std::cout << num_ + i << '\\n'; }
     int num_;
 };

 void print_num(int i)
 {
     std::cout << i << '\\n';
 }

 struct PrintNum
 {
     void operator()(int i) const
     {
         std::cout << i << '\\n';
     }
 };

 int main()
 {
     // store a free function
     std::function<void(int)> f_display = print_num;
     f_display(-9);

     // store a lambda
     std::function<void()> f_display_42 = []() { print_num(42); };
     f_display_42();

     // store the result of a call to std::bind
     std::function<void()> f_display_31337 = std::bind(print_num, 31337);
     f_display_31337();

     // store a call to a member function
     std::function<void(const Foo&, int)> f_add_display = &Foo::print_add;
     const Foo foo(314159);
     f_add_display(foo, 1);
     f_add_display(314159, 1);

     // store a call to a data member accessor
     std::function<int(Foo const&)> f_num = &Foo::num_;
     std::cout << "num_: " << f_num(foo) << '\\n';

     // store a call to a member function and object
     using std::placeholders::_1;
     std::function<void(int)> f_add_display2 = std::bind(&Foo::print_add, foo, _1);
     f_add_display2(2);

     // store a call to a member function and object ptr
     std::function<void(int)> f_add_display3 = std::bind(&Foo::print_add, &foo, _1);
     f_add_display3(3);

     // store a call to a function object
     std::function<void(int)> f_display_obj = PrintNum();
     f_display_obj(18);

     auto factorial = [](int n)
     {
         // store a lambda object to emulate "recursive lambda"; aware of extra overhead
         std::function<int(int)> fac = [&](int n) { return (n < 2) ? 1 : n * fac(n - 1); };
         // note that "auto fac = [&](int n) {...};" does not work in recursive calls
         return fac(n);
     };
     for (int i{5}; i != 8; ++i)
         std::cout << i << "! = " << factorial(i) << ";  ";
     std::cout << '\\n';
 }

.SH Possible output:

 -9
 42
 31337
 314160
 314160
 num_: 314159
 314161
 314162
 18
 5! = 120;  6! = 720;  7! = 5040;

.SH See also

   move_only_function wraps callable object of any type with specified function call
   (C++23)            signature
                      \fI(class template)\fP
   bad_function_call  the exception thrown when invoking an empty std::function
   \fI(C++11)\fP            \fI(class)\fP
   mem_fn             creates a function object out of a pointer to a member
   \fI(C++11)\fP            \fI(function template)\fP
   typeid             queries information of a type, returning a std::type_info object
                      representing the type
